This specification defines a System Level API to provide access to the device alarm settings, which can schedule a notification or for an application to be started at a specific time. For example, some applications like alarm-clock, calendar or auto-update might need to utilize Alarm API to trigger particular device behaviors at specified time points.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document defines a System Level API to provide access to the device alarm settings, which can be used to either schedule a notification or to indicate that an application is to be started at a specific time.
This document was published by the System Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
Example use of the Alarm API for adding, getting and removing and listening to alarms in the device:
How to add an "ignoreTimezone"
alarm?
var alarmId1; var request = navigator.alarms.add(new Date("May 15, 2012 16:20:00"), "ignoreTimezone", { mydata: "bar" }); request.onsuccess = function (e) { alarmId1 = e.target.result; }; request.onerror = function (e) { alert(e.target.error.name); };
How to add an "respectTimezone"
alarm?
var alarmId2; var request = navigator.alarms.add(new Date("June 29, 2012 07:30:00"), "respectTimezone", { mydata: "foo" }); request.onsuccess = function (e) { alarmId2 = e.target.result; }; request.onerror = function (e) { alert(e.target.error.name); };
How to retrieve the information of added alarms?
var request = navigator.alarms.getAll(); request.onsuccess = function (e) { alert(JSON.stringify(e.target.result)); }; request.onerror = function (e) { alert(e.target.error.name); };
How to remove an added alarm?
var request = navigator.alarms.remove(alarmId1); request.onsuccess = function (e) { alert("alarm removed"); }; request.onerror = function (e) { alert(e.target.error.name); };
How to listen to the alarm
event with a callback function
which will run whem an alarm goes off?
navigator.alarms.addEventListener("alarm", function (e) { alert("alarm fired: " + JSON.stringify(e)); }, false);
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.
The EventHandler
interface represents a callback used for event handlers as
defined in [HTML5].
The concepts queue a task, event handler attributes and fire a simple event are defined in [HTML5].
The terms event handler and event handler event types are defined in [HTML5].
Navigator
partial interface Navigator { readonly attribute AlarmManager alarms; }
The alarms
attribute must
return the object through which the alarms functionality can be
accessed.
AlarmManager
AlarmManager
interface exposes
methods to get, set or remove alarms. Alarms are application
specific, so there is no way to see the alarms scheduled by other
applications nor to modify them. This interface also notifies the
application when an alarm goes off, using an event handler
attribute [DOM3EVENTS].
enum TimezoneDirective { "respectTimezone", "ignoreTimezone" }; [NoInterfaceObject] interface AlarmManager : EventTarget { AlarmRequest getAll(); AlarmRequest add(Date date, TimezoneDirective respectTimezone, optional Object data); AlarmRequest remove(DOMString alarmId); [TreatNonCallableAsNull] attribute Function? onalarm; };
The getAll()
method is used
to to retrieve all the alarms added to the device as an array of
Alarm objects.
The error cases must be handled as follows:
error
attribute of the AlarmRequest
to a
DOMError
whose name is
"UnknownError"
, and fire an event named error
at the request.
The add(date,
respectTimezone[, data])
method is used to register an alarm.
date
can is a
Date
object indicating when the alarm should
trigger.respectTimezone
can be
either "respectTimezone"
or
"ignoreTimezone"
to specify if we need to ignore
the timezone information of that Date
object. When
"respectTimezone"
is passed, we will alert that
application when that time happens in that timezone. See
Timezones and daylight savings
section for examples.
data
can be optionally
specified to pass the customized JSON object data for that
alarm. Note that a unique ID will be returned to refer to the
added alarm.The error cases must be handled as follows:
date
argument is in the past, the
implementation must set the error
attribute of the
AlarmRequest
to a
DOMError
whose name is
"InvalidStateError"
, and fire an event named
error
at the request.
DOMError
whose name
is "UnknownError"
is used.The remove(alarmId)
method is used to remove an alarm that has been added in the
device with a unique ID.
If the alarm was successfully removed, the implementation must
set the result
attribute of the AlarmRequest
to true
, and
fire an event named success
at the request. If there was no alarm with the given identifier,
the implementation must follow the same steps but set the
result
attribute of the AlarmRequest
to
false
.
The error cases must be handled as follows:
error
attribute of the AlarmRequest
to a
DOMError
whose name is
"UnknownError"
, and dispatch an error
event at the request.The onalarm
attribute is
the event handler of type Function
for the
alarm
event. This event uses
the AlarmEvent
interface
is fired when an alarm goes off.
Alarm
The Alarm
interface captures
the properties of a registered alarm.
interface Alarm { readonly attribute DOMString id; attribute Date date; attribute TimezoneDirective respectTimezone; attribute Object data; };
The id
attribute must return an identifier for the given Alarm
object that is unique within the
origin. An implementation must maintain this identifier when a
Alarm
is added.
The date
attribute is a
Date
object indicating when the alarm goes off.
The respectTimezone
attribute indicates if the timezone information of the
Date
object is ignored.
The data
attribute optionally defines
the customized JSON object data pass to the alarm.
AlarmRequest
An AlarmRequest
object represents an ongoing operation; it notifies the
application when the operation completes using event handler
attributes [DOM3EVENTS], as well as
a reference to the operation's result. A DOM method that
initiates an ongoing operation may return a AlarmRequest
object that you can use
to monitor the progress of that operation.
This interface is identical to the DOMRequest
interface [DOMREQUEST].
interface AlarmRequest : EventTarget readonly attribute DOMString readyState; readonly attribute any result; readonly attribute DOMError error; [TreatNonCallableAsNull] attribute Function? onsuccess; [TreatNonCallableAsNull] attribute Function? onerror; };
The readyState
attribute
must return the state of this AlarmRequest
. Possible values
are "pending"
and "done"
.
The result
attribute must
return the result of this AlarmRequest
(if any), once the
readyState
is
"done"
and the success
event is
fired.
The error
attribute must
return the error that occurred for this AlarmRequest
(if any). This
attribute is populated when the error
event is
fired.
The onsuccess
attribute
is the event handler of type Function
for the
success
event.
The onerror
attribute is
the event handler of type Function
for the
error
event.
AlarmEvent
The alarm
event is fired when an alarm goes
off.
When this happens, the user agent must queue a task to fire an
event with the name alarm
, which does not bubble and is not
cancelable, and which uses the AlarmEvent
interface, at each
AlarmManager
object that
is affected.
[Constructor(DOMString type, optional AlarmEventInit eventInitDict)] interface AlarmEvent : Event { readonly attribute Alarm alarm; }; dictionary AlarmEventInit : EventInit { Alarm alarm; };
The alarm
attribute must return
the alarm that is going off.
The implementation needs to consider timezones and respect daylight savings. We will provide examples in this section to clarify how non-obvious cases should be handled.
Let's consider an alarm on March 10, 2013 at 2:00am in a timezone where daylight savings time starts at that time (e.g. in San Francisco, CA):
add(new Date(2013, 2, 10, 2, 00, 00), "ignoreTimezone");In San Francisco, CA, clocks are turned forward 1 hour on Sunday, March 10, 2013 at 2:00am due to daylight savings. In this case, the alarm must fire at 3:00am, i.e. one minute after 1:59am.
Let's consider an alarm on November 3, 2013 at 1:10am in a timezone where daylight savings time ends on that date (e.g. in San Francisco, CA):
add(new Date(2013, 10, 3, 1, 10, 00), "ignoreTimezone");
In San Francisco, CA, clocks are turned backward 1 hour on Sunday, November 3, 2013 at 2:00am. In this case, the alarm fires once the first time that the device is running and the local time is past 1:10am on November 3, 2013. After that the alarm is deleted.
Let's consider an alarm set for January 21, 2013 at 7:00am in Pacific Standard Time (PST) with respectTimezone argument set to "ignoreTimezone":
add(new Date(2013, 0, 21, 7, 0, 00), "ignoreTimezone"); // User is currently in Pacific Standard Time (PST)If the user is traveling to New York on that day and currently in Eastern Standard Time (EST), the alarm must fire on January 21, 2013 when it is 7:00am in Eastern Standard Time (EST).
Let's consider an alarm set for January 21, 2013 at 7:00am in Pacific Standard Time (PST) with respectTimezone argument set to "respectTimezone":
add(new Date(2013, 0, 21, 7, 0, 00), "respectTimezone"); // User is currently in Pacific Standard Time (PST)If the user is traveling to New York on that day and currently in Eastern Standard Time (EST), the alarm must fire on January 21, 2013 when it is 7:00am in Pacific Standard Time (PST), that is 10:00am for the user in Eastern Standard Time (EST).
We would like to thank Kan-Ru Chen, Mounir Lamouri, Gene Lian and Jonas Sicking for their work on the API design, as well as the WebAPI/B2G teams at Mozilla [B2G-ALARM].